Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d7 / fac110.arc / FAC.DOC < prev next >

Wrap

Text File | 1990-09-20 | 36KB | 761 lines

Find Area Code (FAC), Version 1.1 Copyright (c) 1990 All Rights Reserved Developed and Marketed as Shareware by Michael K. Molloy 8531 East Dry Creek Place Englewood, CO 80112 CompuServe: 72737, 3237 F I N D A R E A C O D E D O C U M E N T A T I O N Table of Contents o Introduction o Files Included o Installation o Using FAC from the MSDOS Command Line o Using FAC as a Popup TSR Program o Advanced Options and Configuration o Error Conditions o Technical/Compatibility Notes o How to Reach the Author o History of Changes o Alternative Uses o Final Remarks o Quick Reference List of FAC Options Introduction ------------ Find Area Code (FAC) is an MSDOS utility which can quickly locate U.S. and international telephone area codes. FAC performs its search using any part of an area code, city, state, or country and shows matches almost instantly. FAC uses an ASCII data file (FAC.DAT) which you can change, update, or add to whenever you like. There are about 120 U.S. area codes in the database, and about 150 foreign countries with over 450 city codes. You can run FAC from the MSDOS command line or you can make it memory resident (also known as a popup or Terminate and Stay Resident [TSR] program). When you install FAC as a memory resident program, you can choose between a small (7K of RAM) swapping version with a short (less than 2 second) delay while it swaps into memory from disk, or you can have an instantly available popup which requires about 70K of RAM. The program automatically senses and supports all of the 25/43/50 line modes used in most CGA/EGA/VGA video cards and pops up in the current mode, using the screen appropriately for that mode. FAC is distributed on a "shareware" basis. If you try the program, like it, and continue to use it, I ask that you send me $10 to make it possible to improve the program. The program is not "crippled" in anyway (I trust you'll find the program useful and that you'll want to register). Please feel free to distribute the program to anyone you wish. Please don't distribute: 1) modified versions; and 2) registered versions. When you register, you'll receive a disk with a registered copy of the latest version of the program. Your registration is valid for as long as I continue to upgrade the program. Once registered, you are entitled to the latest version anytime for only the cost of sending the disk. You can either send me a SASE floppy mailer with your floppy, or just send me $3.50 and I'll furnish the floppy and mailer. If you send $20, I'll send you the Turbo Pascal 5.5 source code (less code licensed only to me). I'll include the public domain RLINE (public domain) and TP String (shareware) files, as well (see Technical/ Compatibility Notes, below). I can't include any of TurboPower Software's Object Professional units or source code. You should still be able to figure out what's going on and whether you want to get Object Professional (you will!). Obviously, if you purchase the source code it's only for your personal use (you can't distribute it). Contact me for reasonable site license and quantity discount information. Files Included -------------- This package, distributed as FAC110.ZIP, has the following files (the " ~ " means the file MUST be present to run the program): README.1ST - Description of program and summary of features FAC.EXE ~ The executable program FAC.DAT ~ The Area Code database, an ASCII file which you can modify in any way you like. FAC.DOC - Documentation (you're reading this now) Installation ------------ You can put Find Area Code's files in any directory. The FAC.EXE and FAC.DAT files can be anywhere on the disk as long as you set a path to them with the MSDOS PATH statement. Note that FAC.DAT need not be in the same directory as FAC.EXE as long they are both on the PATH. You need about 90K of disk space and 64K RAM to run the program from the MSDOS prompt (non-TSR mode). To use the program as a swapping TSR you must have about 220K of free disk space (including space required for swap files). A hard disk is recommended, but isn't required if you don't mind the program running quite a bit more slowly. Using FAC from the MSDOS Command Line ------------------------------------- First, you must know how to invoke FAC from the MSDOS command line prompt. Type "FAC" then ENTER and you'll see a complete list of options you have for using FAC. Don't be alarmed at all the options. FAC is very simple to use and really requires only one thing--a string to search for. All the options are for more advanced use. FAC is designed to be very easy to use without reference to documentation or help screens. FAC will search for area code information only if you enter the search string as an MSDOS parameter right after the program name. For example, suppose wanted to know the area code for Boulder, Colorado. At the MSDOS prompt, type: "FAC boulder" (without the quotes, of course) then press ENTER. The program will start, a window will popup on the screen, and the program automatically begins its search. Almost instantly, you'll see information about the area code for Boulder. The first column in the display window has the 3 digit area code 303 (international area codes aren't necessarily 3 digits). The next column shows the 2 character postal abbreviation for Colorado, CO. The third column shows the full name of the state. The last column shows the major cities in this particular area code. Notice Boulder appears in this list. When you've finished with the program, just press Esc and you'll exit back to MSDOS. Let's take another example. Suppose someone leaves you a note to call someone in a 309 area code. You don't recognize this area code and it's inconvenient to look up the area code in the phone book. You type "FAC 309" then press ENTER. Almost instantly, you learn that the 309 area code includes Peoria, Molina, and Rock Island, Illinois. Searching for an international area code is almost exactly the same. Just type in a city name, say Paris. The program will display the country code in the first column, the country name in the next column (there is no postal abbreviation for most foreign countries), and a list of major cities and city codes for that country in the last column. Each city code is listed in parentheses immediately after the city name. So you know the country code for France is 33 and the city code for Paris is 1. You get the idea. By typing "FAC X" where X is any alphanumeric string, you can quickly search the area code database. You can search by area code, state postal abbreviation, state name, country, city, or any portion of thereof. The search string can be in any combination of upper or lower case letters and numbers. NOTE: If you use only two characters, the program assumes you want to search for two-letter state postal abbreviations which appear only in the first 7 characters of each line. Once you're inside the program, you can search for other area code information by entering another search string at the prompt. To edit your entry, press Backspace, or press Esc to erase your entire entry. If you press Esc once more, you'll exit the program. You can make any number of searches before exiting the program. Remember, just press Esc to exit the program (Ctrl-C or Ctrl-Break will also exit the program). Sometimes, your search string will find more information than can be displayed in the window. If the screen fills up with information, the program will pause and prompt you to press the Esc key to stop displaying information from the current search, or press any other key to continue displaying information. If you press Esc to stop displaying information, you'll be returned to FAC's prompt. Pressing Esc once more will exit the program. Once you've experimented with FAC, you may notice that sometimes it pops up in the upper half of your screen and sometimes it pops up in the lower half. Why? FAC looks at where the cursor is positioned and brings up the FAC window in the opposite half of the screen you're working in. This insures the program doesn't obscure something you may need to see while you're using the program. Using FAC as a Popup TSR Program -------------------------------- More often than not, when you're at your computer and you need area code information, you're in the middle of doing something else. To use FAC as described above, you must save your work, exit the program you're using, then invoke FAC. FAC would tell you what you need to know, then you would have to restart your original program, go back to where you left off, and try to go back to work. It would be much more convenient if you could simply have FAC immediately "popup" over whatever you're doing, give you the information you need, then go away, leaving you exactly where you were. Not only would it be more convenient, it would save a lot of your valuable time. FAC can do this. All you have to do is tell FAC to install itself as a "popup" or memory resident program. You'll also see this type of program called a TSR, which stands for Terminate & Stay Resident. A TSR is installed or loaded once from the MSDOS command line. It stays in memory even while you're doing other things, and watches to see when you press a special key or key sequence to activate it. This special key sequence is known as a "hotkey". When you press the hotkey, the program starts. Here's how to install FAC as a memory resident, popup program. At the MSDOS prompt, type: "FAC /I" (without the quotes) then press ENTER. FAC will then install itself in memory as a TSR. When it has successfully installed itself, it will describe how it has been installed. In this case, you will use FAC's defaults. Once you've installed FAC as described above, you can press FAC's hotkey to pop it up wherever you are. FAC's hotkey is <Alt><LeftShift><F>. To press this key sequence, press and hold the "Alt" key, press and hold the Shift key on the left side of your keyboard, then press the F key. As soon as all three keys are pressed, FAC will "wakeup" and activate itself. FAC will draw its window on the screen right over the top of whatever you're doing. Don't worry. When FAC is done, it will return the screen to exactly the way it found it. When you invoke the TSR version of FAC as installed above, it works somewhat differently than it does when you start it from the MSDOS prompt. Recall that when you run the program from the MSDOS prompt, you must enter a parameter (search string) so FAC knows what to search for. When FAC operates as a TSR, it can read the text string (state, area code, city, etc.) you want to search for right off the screen by looking at the word "under" or to the left of where you have the cursor positioned! (You can turn off reading the search string from the screen by using the /G switch. See Advanced Options and Configuration.) If the cursor isn't in a word or just to the right of a word, no search string will be passed to FAC, but it will still pop up. So, what happens? You press the hotkey, FAC pops up over your work, reads the text "under" the cursor, and immediately begins its search. After it finds and displays a match, it prompts you for another search. Now the program operates exactly the way it does when used from the MSDOS prompt. When you want to exit, press Esc, and FAC will collapse its window, and restore your screen and cursor location exactly the way it appeared when you pressed the hotkey. You may have noticed that when you pressed the hotkey, a reverse video message appeared on the bottom of the screen which said "Swapping in..." Similarly, when you pressed Esc to exit the program, "Swapping out..." appeared. These messages tell you the program is swapping into and out of memory (RAM) from disk. Why does the program do this? Swapping TSRs are relatively new. When they install, they take a snapshot of the complete program and write it out to a "swap file" on disk, then free up all but a tiny portion of memory (which holds the portion of the program which watches for the hotkey and then does the actual swapping to/from disk). When swapping TSRs pop up over your existing program, they may also have to take a snapshot of your application and write it to disk before it swaps the rest of the TSR in. So why do we want to put up with all this swapping in and out? Doesn't this cause delays? Why can't the program just pop up instantly like my other TSRs? Well, like everything else in the world, there are tradeoffs. In order to run full-featured, advanced programs, it takes memory (RAM). The more full-featured the program, the more memory it takes. Unfortunately, memory is a limited resource and "full-featured" often translates to "memory-hungry." FAC has many features but still only requires about 70K of RAM to run. This isn't a problem if FAC is the only program you want to run, but it's a big problem if you want FAC to be loaded as a TSR at the same time you're running other (full-featured) programs. When FAC is installed as a swapping TSR, it only requires about 7K of RAM to watch for you to press the hotkey and then swap what you're doing out and swap itself in. With all the other TSRs you use and the other programs you run, you need all the help you can get. The TSR swapping technology FAC uses helps you optimize all the memory you have with very little impact on how you use the program. As computers continue to become faster and more powerful, you'll see more and more swapping TSRs. The time you spend waiting on swapping is relatively trivial compared to the time it takes to leave your application, then return. On XT class computers, swapping delays are only about 1 or 2 seconds. On 286 class computers, delays are usually about 1 second. On 386 and 486 class computers, delays are usually less than .5 seconds. Of course swapping delays can be affected by a wide range of hardware and software variables. Fast hard disks with 1:1 interleaves and high data transfer rates make a huge difference, even when used on an 808X CPU. If you're able to use a RAM Disk, or disk caching (hardware or software) you'll find swapping delays to be negligible or even unmeasurable. See the section below on Advanced Options and Configuration for information on how to reduce swapping delays. The bottom line is, I think the tradeoffs (disk swapping delays) are completely acceptable given the savings in memory. I think you'll think so, too! (Note: future versions of FAC should allow swapping to either extended or expanded memory.) Advanced Options and Configuration ---------------------------------- FAC has several different options or "switches" you can use to customize the way FAC works when you invoke the program or install it as a popup. Most of FAC's command line switches relate to its installation as a TSR. Again, FAC is designed to be very easy to use, and you may be perfectly happy with FAC's performance when you use its default options. Switch options are always preceded by either a "/" or a "-" and can be upper or lower case letters. Remember, to see a complete list of all FAC's options, just type "FAC" at the MSDOS prompt and press ENTER. The "/X" Switch --------------- Used for both non-TSR and TSR. This option or program "switch" applies to FAC when run from the MSDOS prompt (non-memory resident mode) or when you install it as a popup. If you use the "/X" switch, FAC will disable its use of exploding windows. Exploding windows don't change the way the program searches or the way you use it, it just changes how the program looks when it starts and finishes. If you want to disable exploding windows when you run the program from the MSDOS command line (non-TSR), just put the /X switch after your search parameter. Example: "FAC boulder /x" When the program starts, the window would appear instantly on the screen instead of being exploded onto the screen. The "/I" Switch --------------- Used to install FAC as a swapping or non-swapping TSR. You've already seen that the /I switch is used to install FAC as a memory resident program. If you use /I by itself, the program will install itself using several predefined defaults, all of which can be changed by using other switches. If you use /I alone to install FAC, the following defaults are used: - Swapping to disk is enabled. - Messages which tell you swapping is happening are enabled. - The disk and directory path FAC uses for swap files is the same directory where FAC found FAC.DAT. - Exploding windows are enabled (see the /X switch above). After you use the /I switch to install FAC, you will see a status message which describes the state of each of the above defaults. Note that if FAC is already installed, you won't be able to install a second copy. If you try to install it again, you'll get an error message and the installation will abort. If you don't have enough disk space for the swap files, you'll get an error message and FAC won't install as a TSR. After you install FAC as a TSR, don't move or rename the FAC.DAT file or you will probably get dumped from the TSR when you try to use it. Please note that you can't pop up FAC when you're using a program which is currently in graphics mode. If you try to pop it up, you'll hear a beep and nothing else will happen. Also, be aware that since FAC swaps the currently running program out so it can become active, you could have a problem with some programs, especially communications programs. In this case, you should run the program in non-swapping mode (/N). It still isn't advisable to pop up any TSR when a communications program if data is coming in or going out. FAC should work fine with most other TSRs. The only problem you may encounter is when you don't load FAC last among other TSRs. This won't hurt anything, but you may not have access to your other TSRs when FAC is swapped in (since it may have swapped the other TSR(s) out of RAM). If FAC isn't in use, or it's been installed as a non-swapping TSR, you shouldn't have a problem with TSRs loaded after it. Don't attempt to install FAC while you're "shelled out" of other programs. For example, you can drop temporarily to MSDOS from many programs, but you should never try to install FAC while you're doing so. This also applies to many menuing programs like PowerMenus and AutoMenu. These programs can leave a portion of themselves in memory. You should never try to install FAC as a TSR from any menu program. Completely exit from any other program before attempting to install FAC as a TSR. You may run FAC from the MSDOS prompt (non-TSR) while shelled out of another program if you wish. Example: "FAC /I" This would install FAC as a TSR with the defaults described above. What follows is a more detailed discussion of these defaults, how you can change them, and why you might want to. The "/N" Switch --------------- Used with /I to install FAC as a non-swapping TSR. The /N switch says, "don't use the swapping TSR mode; keep the entire TSR in RAM." This will give you instant access to FAC when you press the hotkey, but requires about 70K of RAM. If you have plenty of RAM, you need FAC to be available instantly, and you use programs which won't miss the memory FAC requires in this mode, use the /N switch. The default is a swapping TSR. Example: "FAC /I /N" This would install FAC as a non-swapping TSR. The "/M" Switch --------------- Used with /I when installing FAC as a swapping TSR. The /M switch says, "don't put the swapping in/out... messages at the bottom of the screen when swapping." The program doesn't work any differently, except that you won't see the messages. If you use a RAM disk for swapping, the swapping messages might be an unnecessary distraction. The default is to have swapping messages appear. Example: "FAC /I /M" This would install FAC as a swapping TSR, but swapping messages would be disabled. The "/P" Switch --------------- Used with /I when installing FAC as a swapping TSR. The /P switch, when followed by a complete path specification, says, "put the swap files in the specified disk/directory." The main reason you would use this switch would be to tell FAC to use a RAM disk. If you have a RAM disk, with at least 150K of space, you should use the /P switch to significantly speed up swapping. If you use /P to swap to RAM disk, you may wish to use the /M switch to disable the swapping in/out messages. Whether you use the /P option or not, FAC generates either one or two swap files, named FAC-SWP1.$$$ and FAC-SWP2.$$$, each about 70K in size, located wherever FAC.DAT was found (unless you specify otherwise with the /P switch). These files are marked with both System and Hidden attributes to make it less likely you will accidentally delete them. If they are deleted after FAC is loaded, and you try to pop up the program, you'll get an error message and have to reboot. When you successfully unload FAC, the swap files are deleted. If you reboot or turn your machine off, the file(s) will remain, but will be written over the next time FAC is loaded as a TSR. The default is to put swap files in the same disk/directory where FAC.DAT was found. If you aren't sure where this is, run FAC with no parameters and look at the default determined at run time. Examples: "FAC /I /Pd:" "FAC /I /Pc:\junk The first example would install FAC as a swapping TSR with the swap files located on the D: drive. The second example would use a swap file directory called C:\JUNK. The "/G" Switch --------------- When used with /I; don't get search strings from the screen in TSR mode. The /G switch says, "When you popup FAC, don't read the text to search for off the user's screen; just ask for a string." This switch prevents you from grabbing the search string and requires you to enter it yourself. The default is to read the screen for the text to search for. Example: "FAC /I /G" This example disables reading the text from the screen when FAC is popped up. The "/U" Switch --------------- Attempts to uninstall FAC (in TSR mode) from memory, and delete swap files, if they exist. The /U switch says, "If it is safe to do so, remove FAC from RAM as a swapping or non-swapping TSR, free up associated memory, and delete any swap files which may have been created." Use the /U switch if you need to uninstall the program. "If it is safe to do so" means just that. If FAC isn't installed as the last TSR, you won't be able to uninstall it. (You may be able to uninstall FAC by using something like the Mark/Release TSRCOM utilities, but even then, you must remove FAC and all TSRs loaded after it. If you plan to frequently uninstall FAC you should load it last. Of course if you load FAC last, then you won't be able to unload TSRs loaded before it. Naturally, you can uninstall any TSR by rebooting your machine. Error Conditions ---------------- FAC is very friendly and shouldn't give error messages unless there's really something you need to fix. Here are some error messages FAC could generate and why you might get them: - "Error while trying to find/open FAC.DAT" Make sure FAC.DAT exists and that the disk and directory containing FAC.DAT is on your MSDOS path. - "FAC isn't loaded!" You've tried to uninstall FAC (as a TSR) when it wasn't previously loaded. Use the /I option to install it. - "Unable to unload FAC. Probably isn't safe to do so!" This isn't really an error message; it just means that the program can't uninstall itself, probably because there's another TSR or program loaded after it. Try rebooting if you have to unload it. - "XXXX not found." This, too, isn't really an error message. You'll get this message any time you searched for string and it wasn't found. The string you're searching for may not be in FAC.DAT or you may need to check your spelling. - "FAC is already memory resident!" You're trying to install FAC after it's already been loaded. Use FAC /U to uninstall it. - "Unable to go TSR. Do you have enough swap file disk space on X:?" This message means FAC couldn't go TSR, probably because you don't have enough RAM, or you don't have enough disk space for the swap files. - "Couldn't make window!" There was a memory allocation error when FAC tried to draw its window. You probably don't have enough RAM to run FAC. Technical/Compatibility Notes ----------------------------- Find Area Code runs on IBM PC compatibles (clones) using MSDOS 3.X. I've not tested the program under MSDOS 4.X. I'm pretty sure the program won't work with DOS 2.X since 2.X handles paths differently. It might work if you're in the same directory as the data file. One of the reasons the program searches so quickly is RLINE, Don Strenczewilk's excellent Turbo Pascal OOP text file handling unit. RLINE allows you to define a "file of lines" object. In addition, FAC can search at a rate of over 600 lines per second on an XT with a slow hard disk! Thanks to Don for graciously donating his code to the public domain! Another reason the program is so fast is due to Richard Winkel's TPSTR. TPSTR (Ver 1.21) is a Turbo Pascal Unit with about 30 REXX-like string procedures and functions, all carefully crafted in assembly language. Richard's licensing fee is very reasonable ($10) and you get all the Turbo Pascal and assembly source code. Highly recommended! The excellent TSR swapping system and windowing comes from Object Professional 1.02 from TurboPower Software. If you do any programming in Turbo Pascal 5.5, you owe it to yourself to use Object Pro! How to Reach the Author ----------------------- Michael K. Molloy 8531 East Dry Creek Place Englewood, CO 80112 CIS: 72737, 3237 I also frequent the MicroManiac!, Tom Gettys' fantastic Wildcat BBS (303-673-9470) in Lafayette, CO. His board should always have the latest version of Find Area Code (and hundreds of other fresh uploads!). History of Changes ------------------ 1.0 - Experimental version; not released to general public 1.1 - Rewritten using Object Pro; major overhaul of program and documentation NOTE: If I get registrations and user support for this program, I'll add other valuable features in future versions: - XMS/EMS swapping support - Resizable/Movable window - Install/clone program to set user defaults (colors/hotkey/etc.) - Soundex string matching (get a match even on misspelling) - Multiple data file handling ("subject" databases?) - Mouse support? - You tell me!! Alternative Uses ---------------- You may thought to yourself as you used FAC, "Hmmm, if I can pop FAC up anywhere as a tiny TSR, and if I can change the contents of the FAC.DAT file, why can't I put my own personal information into it and quickly and conveniently search for it when I need it?" You can, and I hope you will. I think the ease of modifying FAC's database is a very valuable feature. In fact, one of the reasons I decided to write "yet another area code finder" was the frustration I had with the fact you couldn't modify, correct, update, or add to some of the other area code program data files. My own personal use of FAC goes far beyond just using it to hunt down area codes. Here's what I do. I have (you probably do, too if you're any kind of computer nut) a database of friends and relatives with which I maintain a quick reference phone list. Periodically, I use my database program to generate a report which I print to disk. The report looks something like this: John Doe 555-555-5555 1234 Anywhere St., Anyplace, CO 12345 Joe's Software Shop 555-1234 (open 24 hours) Jay's Hardware Emporium 555-9876 (Closes at 6pm) Jim Smith 555-0000 (Keep trying; has teenagers on phone) . . . (you get the idea) I use an editor to paste the ASCII information into the front of my FAC.DAT file, and presto! I have a 7K popup database of our family and friends. I put the information at the front only to improve search times for the information I need most frequently; it can be anywhere, in any format, in any order since every character of the entire FAC.DAT file is searched every time (except when your search string is only 2 characters; that tells the program you're searching for a state postal abbreviation in the first 7 characters; be careful with that!). Obviously, if you change the data file to reflect your own data, it could be used for almost anything. Just remember, the program is line-oriented--all the information for one "record" must be on the same line. Each line in the data file is limited to 119 characters. If lines are longer than 119 characters, they'll be truncated when they are displayed. The program will automatically wordwrap lines of up to 119 characters when the "record" is displayed. I guess the way I use FAC makes it kind of a "poor man's personal information manager (PIM)". I've found that FAC is far superior to LIST and other text file handling programs when it comes to ease of use and search speed. FAC certainly isn't offered as any kind of free format database package, but I think it bridges an important gap between a full-blown database application and a tattered piece of paper taped above your computer desk. I think this capability gives FAC significant "value added." I hope you agree and you see another reason to support the program financially with your registration. Use your imagination! If you come up with radical or useful new applications for Find Area Code "engine", please let me know. Final Remarks ------------- Many thanks to my wife, Bobbea, for her friendship, love, and support in every aspect of my life. Thanks to Tom Gettys for his patient and valuable beta test feedback and for having the best BBS in Colorado! I've made every effort to provide the correct area codes and foreign country city codes. If you find errors or additions, please send them to me on CompuServe. If FAC doesn't do what you think it should, or you'd like for it to do something else, I would be happy to develop a customized version of the program for anyone who wants one (for a reasonable fee). I'd appreciate bug reports, new feature requests, comments, performance problems, constructive criticism, suggestions, additions, and/or corrections regarding Find Area Code. Enjoy! Mike ------------------------------------------------------------------------ Quick Reference List of FAC Options ----------------------------------- FAC (Shows brief help information) FAC <String> (Searches for String [can be any part of or all of a City, State, Country, or Area Code] If String is 2 characters then a search on U.S states only is assumed) Not a TSR FAC /I (Loads popup/TSR with defaults: - Swapping on - Swapping messages on - Swap file path = same path FAC.DAT found on - Exploding windows on - Read search string from screen FAC /I /N (Loads popup; no swapping [instant popup mode but requires 70K RAM]) FAC /I /M (Loads popup; suppresses swapping messages) FAC /I /Pc:\temp (Loads popup: path for swap files = c:\temp Specify RAM disk if available/possible) FAC /I /G (Don't read text from screen on popup [When used with other parameters]) FAC /X (Don't use exploding windows [When used with other parameters]) FAC /U (Unloads popup from memory, if possible; deletes swap files) ------------------------------------------------------------------------ *** End of FAC.DOC ***